Cloudinary で画像を更新したら – 変換画像とキャッシュの削除

Cloudinaryの画像や動画アセットを更新した際の変換やキャッシュの動きについて解説します。

#Cloudinary

#SaaS

#デザイン

#画像処理

Ito ma

2023.12.15

Cloudinaryを利用していると、既存の画像・動画などのアセットに変更を加えたり、削除して配信を止めたりというケースがあるでしょう。

そして、変更や削除をしたのにうまく更新が反映されない、という悩みはよく聞きます。

高速配信を実現するために Cloudinary では CDN が利用されているので、そのキャッシュが残っていることがたいていの要因ですが、実際に行っている操作やその方法にもよります。

先日のブログでCloudinaryにおける変換やキャッシュについて、仕組みを解説しました。

これを踏まえて、今回のブログではアセットの更新時に変換（派生）やキャッシュがどのような動きとなるか、まとめてみようと思います。

※前回と同じく「画像」と書いていますが、動画や他のアセットでも基本的に同様です。

Cloudinaryでのアセット更新

まずアセットへ更新を加えるというと、

もう使わなくなった画像を削除する
同じ名前で違う動画をアップロードし直す
画像のタグを付け替える（タグに応じて異なる変換をしている例）

といったケースがあります。

基本的には、これらの更新時に派生画像は削除され、CDNキャッシュがある場合は保持期間を過ぎてから削除されるもので、更新はやがて反映されます。

逆に言うと、ブラウザのキャッシュがなくても、すぐに新しい画像や変換が配信されるとは限らないのです。

ケース 1：画像を削除するのでURLもすぐ無効化したい

API の場合

アセット削除用に2つのメソッドがあります。

1つのアセットを削除する destroy メソッド (Upload API)でinvalidate=Trueを付与して実行
複数アセットを削除できる delete_resources メソッド (Admin API)でinvalidate=Trueを付与して実行

いずれもデフォルトで派生画像は削除されますが、キャッシュは保持期間残るので、すぐURLを無効化するには invalidate オプションを付与してCDNキャッシュを無効化する必要があります。

なお、Admin API には制限（後述）があるので、できればアセットIDを特定して1を並列実行するのがベターです。

コンソールの場合

削除は Media Library や Media Explorer から複数選択でできます。

もっと大量に削除する場合は、設定画面の右側にある Bulk delete というメニューから、作成日やタグ、プレフィックスで指定した一括削除ができます。

いずれの場合でも、派生画像はすべて削除されます。また、コンソールでのアセットの変更・削除操作には常に invalidate=True が含まれるため、アセットに紐づくキャッシュもすべて無効化されます。

ケース 2：同じ名前で動画をアップロードし直してすぐ反映させたい

同じパブリックIDでアセットを更新したい場合、上述の方法で削除してから再アップロードするか、次のように上書きアップロードする方法があります。

API の場合

upload メソッド (Upload API) でoverwrite=Trueとinvalidate=Trueを付与して実行すれば上書きアップロード、派生画像の削除とキャッシュの削除ができます。

コンソールの場合

上書きする場合は、選択されているアップロードプリセット（=アップロード時の設定セット）に注意しましょう。プリセットの設定により、同じ名前でアップロードすると自動的にIDを調整して上書きを避けるようになっている可能性があります。

上書きでも削除/アップロードでも、ケース1と同様に派生画像はすべて削除され、アセットに紐づくキャッシュも無効化されます。

ケース 3：タグに応じた変換をしている画像で、タグを付け替えて新しい変換を反映させたい

本ブログのようにアセットに与えられたタグに応じて条件分岐で異なる変換をさせていて、アセット自体は変えずに紐づくタグのみを変更するケースです。

コンソールの場合

タグの変更もアセットへの変更操作とみなされ、派生画像が削除され紐づくキャッシュもすべて無効化されます。

API の場合

コンソールと違い、(1) タグの変更、(2) 派生画像の削除または再生成、そして (3) キャッシュ無効化がまとめて実行されないので、それぞれ検討する必要があります。

まずタグの変更用には2つのメソッドがあります。

1つのアセットのタグを更新できる explicit メソッド (Upload API) で tags オプションに新しいタグ設定を指定し、invalidate=Trueを付与して実行
複数アセットのタグを編集できる tags メソッド (Upload API) を実行

tags のメリットは、既存で付与されているタグに対して追加・削除といった操作ができることです。ただし (2)(3) 派生画像とキャッシュに関するオプションはないので、別途実行が必要です。

一方、explicit を使えば、eager オプションに変換パラメータを指定することでその変換の派生画像を再生成することもできるので (1)〜(3) が一気にできます。
ただし、派生画像の事前生成は配信速度を上げるのに役立つ一方で、実行時点で Cloudinary の変換キャパシティを消耗することになります。数が多い場合は一気に生成することでライセンス量を超えて追加料金となる可能性があるので、これを避けたければ eager オプションは使わずに (2) 派生画像の削除を別途実行して、ユーザアクセス時に再生成させるようにします。

(2)(3) 派生画像とキャッシュの削除には、delete_resources メソッド (Admin API)でkeep_original=True, invalidate=True を付与して実行します。
さらに transformation オプションに変換パラメータを指定することで、関連する変換の派生画像だけを削除することができ、余計な変換キャパシティを使わずに済みます。

要望に合わせて、タグ変更のAPIと組み合わせて実行してください。

Upload & Admin API の違い

レートリミットの違い

Upload API には実行の上限がなく、大量リクエストしても安全です。
一方、Admin API は1時間あたりのリクエスト数が制限されています。具体的な値はコンソールの設定画面から確認可能です。

無効化するURLパスの違い

Cloudinaryでは以下のようなURLの構成で、このうちバージョン項目（vの部分）をデフォルトとは異なる形式で利用している場合、そのキャッシュは無効化されない可能性があります。

https://res.cloudinary.com/CLOUD-NAME/image/upload/v1/path/to/file.jpg

Upload API （現時点でexplicitメソッド除く）の場合は、surrogate key という機能がサポートされており、invalidate=True オプションを付与した時にすべての形式のURLがキャッシュ無効化されます。
Admin API では、本機能がサポートされていないため、レガシーの動きでデフォルトのバージョン形式のURLしかキャッシュ無効化されません。

▼ バージョン項目について詳しくは以下ブログを